/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 * Created on 15.04.2004
 * @author Andreas Prlic
 *
 */

package org.biojava.services.das.registry ;

import java.sql.SQLException;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.biojava.dasobert.das.Capabilities;
import org.biojava.dasobert.das.DasSpec;
import org.biojava.dasobert.dasregistry.DasCoordinateSystem;
import org.biojava.dasobert.dasregistry.DasSource;
import org.biojava.dasobert.dasregistry.DasValidationResult;
import org.biojava.services.das.dao.DasServer;



/** The interface for DasRegistry implementations
 *
 * @author Andreas Prlic
 */

public interface DasRegistry {
	
    //public static String SPEC1_5="spec1.5";
    //public static String SPEC1_6="spec1.6";
    /** 
     * return list of available DAS sources 
     * @return a list of all DAS sources
     * @throws Exception 
     * 
     */
    public List<DasSource> listServices() throws Exception ;
    
    public List<DasServer> listServers() throws Exception ;
    
    /** general interface to search the registry : 
     * @param capability 
     * @param category 
     * @param name 
     * @param organism 
     * @param labels 
     * @return  das sources that match the requested keywords
	
    */
    public List<DasSource> findService(String capability, 
				   String[] category, 
				   String[] name,
				   String[] organism,
				   String[] labels, String spec);		
    
    
    /** returns all DAS sources that match to a certain keyword 
     * @param keyword 
     * @return all das sources that match the requested keyword
     * @throws Exception */
    public List<DasSource> keywordSearch(String keyword) throws Exception ;
    

    /**
     * register a new service in DAS database 
     * 
     * return: int which provides an Exitcode.
     * 1 - service has been registered successfully
     * 0 - unknown error occured
     * 2 - server already in database, not registering a second time
     * 3 - server failed validation test
     * 4 - database error -  could not add server to database
     * 5 - unknown capability - one or several of the capabilities are unknown.
     * 6 - adminemail not a valid email address	 
     * 7 - dasurl not valid
     * 8 - description not valid
     * 9 - coordSystem not valid
     * 10 - capabilities not valid
     * 11 - testCode not found
     * 12 - nickname already in use / invalid nickname
     * an int > 1000 ; a random number which serves as key required to remove a server from the registry
     * @param url 
     * @param nickname 
     * @param adminemail 
     * @param description 
     * @param coordinateSystem 
     * @param capabilities 
     * @param labels 
     * @param helperurl 
     * @param testCodes 
     * @return  status code of key to edit / delete server
     */
    public int registerService(String url, 
			       String nickname,
			       String adminemail, 
			       String description, 
			       String[] coordinateSystem,
			       List<String> capabilities,
			       String[] labels,
			       String helperurl,
			       String[] testCodes			       
			       ,DasSpec spec, String queryUri) ;

  

    /** retreive all possible Labels of DAS services 
     * @return all labels*/
    public String[] getAllLabels();

    /** retrieve all possible Capabilities of DAS services 
     * @return all capabilities
     * @throws Exception 
     */
    public String[] getAllCapabilities() throws Exception;
    

    /** retrieve all available CoordinateSystems 
     * @return coordinate systems
     * @throws Exception */;
    public List<DasCoordinateSystem> getAllCoordinateSystems() throws Exception ;

  

    /** removes a service from the registry 
     * the key is the "password" only available to the server administrator 
     * an int is returned, wich provides the status of the request:
     *  1: successfully renewed
     *  2:  incorrect key ;
     *  0: some other error occured;
     * @param serverurl 
     * @param passkey 
     * @return flag is success
     */    
    public int removeService(String serverurl, String passkey) ;

    /** send an email to the admin of server url, reminding him of his
     * key required to delete a server from database
     * To prevent flaming a key can only be sent once in a while.
     * returns:

     *  1  : successfully sent mail
     *  2 : if the time difference is not big enough, and no  mail has been sent
     *  3: some other error occured;
     *  4: the email address specified in >sendmailto< does not match the one stored in the registry for this server.
     * @param url 
     * @param sendmailto 
     * @return key to remove / edit server
     */
    public int requestKey(String url,String sendmailto) ;

    /** return all available Organisms in  database 
     * @return all organisms 
     * */
    public String[] getOrganismsByName();

    /** get available categories 
     * @return all coord sys types
     * 
     * */
    public String[] getCoordSysTypes();


    /** returns all coordinate systems of this type 
     * @param type 
     * @return string arr 
     * */
    public String[] getCoordSysByType(String type) ;

    /** get a DasSource based on its unique db identifier the public
     * instance has Auto_Ids that start with DASSOURCE:12345; public
     * look like XYZ:12345, where the XYZ prefix can be configured in
     * the config file.
     * @param auto_id 
     * @return DasSource
     * @see DasSource
     *
     *
    */
    public DasSource getDasSource(String auto_id);

    
    /** return errors that have been found during validation 
     * @return the message created during validation
     * */
    public String getValidationMessage() ;

    /**
     * method needed so we can search the organisms alphabetically as there are now so many nearly 400,000 rather than the old number of 60
     * @param startOfName
     * @return
     */
	public String[] getOrganismsByName(String startOfName);

	public List<DasCoordinateSystem> getCoordSysByName(String startOfName)throws Exception;
	
	/**
	 * if the auto_id exists in the registry set the valid capabilities
	 * @param auto_id
	 * @return
	 */
	public int updateValidCapabilities(DasSource source);

	public int updateTypes(List<Map<String, String>> types, DasSource ds);

	public int updateSpecification(String spec, DasSource ds);

	/** renew Lease for server
     * an int is returned, wich provides the status of the request:
     *  1: successfully renewed
     *  0: some other error occured;
     * @param url 
     * @return return  flag is successful
    */
	public int renewLease(String url, boolean allValid);

	public String storeServer(String sourcesPath, String openId, String description)throws SQLException;
	
	public List<DasSource> getDasSourcesForServerURL(String serverRootUrl);
	/**
	 * update the times it took to get responses for the capabilities for each data source
	 * @param times
	 * @param ds TODO
	 */
	public void updateTimes(Map<Capabilities, Long> times, DasSource ds);
    
}
